
 HBP10GM - software MIDI synthesizer
 ===================================

 HBP10GM is a software MIDI synthesizer.
 Why it is called HBP10GM? Apparently just about all MIDI-synthesizers
 have name likes DB50XG, PSR6700, QS300 or AWE32GM, so why not?
 Strictly speaking, 'GM' is supposed to mean 'General MIDI', but the
 HBP10GM synthesizer doesn't quite live up to the General MIDI standard.

 Notice that the sound-quality when using the supplied samples/patches
 is quite low, as most of the instruments use a built-in
 sawtooth-waveform! It is up to you to find suitable samples to use
 with the synthesizer...

 The synth supports multiple ports; that is, you can play multiple
 MIDI data streams simultanenously, eg. you can play from MidiWorks or
 Monolith at the same time as converting a MIDI file to samples in a
 taskwindow. Most of the user-interface handles the default port, which
 is also the only port for which the synth provides facilities such as
 playback through the Acorn 16 bit soundcard, or installation as a
 MIDISupport device. The built-in scheduler also only works with the
 default port.


 Copyright
 ---------
 This software is copyright Henrik Bjerregaard Pedersen, 2000-20001
 and has been released under the GPL (any version).

 email:  henrik@login.dknet.dk
 www:    http://login.dknet.dk/~henrik/


 In use
 ------
 You can configure the synthesizer to use a lower output-frequency
 and allow fewer simultaneous notes (polyphony) if you think it is
 using too much of the CPU.

 If you have the MIDI4 module and the MIDISupport module, the HBP10GM
 synthesizer can be used just like any other MIDI device; if you don't
 have the MIDI4 module or the MIDISupport module, you can either use
 the MIDI500 module which is included or you can use programs which
 can control the synthesizer directly, such as the supplied programs.

 MIDISupport is a commercial module from ESP. The HBP10GM can use the
 MIDISupport module to install itself as a MIDISupport device; if so,
 the HBP10GM will be available just like any other MIDI-device and can
 be used from eg. MidiWorks or MelIDI etc.

 MIDI500 is a free alternative to the Acorn/ESP MIDI module. It doesn't
 provide all the features of the MIDI module, but enough to allow you
 to play through the HBP10GM synth from MidiWorks (and probably also
 from other program).
 As the module doesn't implement the entire MIDI API, there probably
 are some application that won't work with the MIDI500 module.


 Input
 -----
 The HBP10GM accepts MIDI input, not MIDI file input!
 A program is included for playing back MIDI files.


 Output
 ------
 The HBP10GM is not primarily intended for playing the notes you pass
 to it - more for generating the samples that should be played to hear
 the notes you've passed to it.
 The output samples can be read using SWI HBP10GM_ReadSamples.
 However, if you have an Acorn 16 bit sound card, the HBP10GM can use
 this to play the samples (use '*HBP10GM_Playback 1').


 Giving MIDI events to the HBP10GM
 ---------------------------------
 There are a number of ways MIDI events can be timed to be sent to the
 output at the correct time:

 a) you can use MIDI4+MIDISupport
 b) you can use SWI Sound_QSchedule to schedule commands/events
 c) you can use SWI HBP10GM_Schedule to schedule commands/events
 d) you can use MIDI500

 a) is the best solution as it allows the HBP10GM to work with any
    MIDI sequencer, MIDI file player etc.
 b) has the advantage that it integrates nicely with the normal
    soundsystem
 c) is useful if you want to read the samples in non-realtime; it
    can also be used in conjunction with '*HBP10GM_RealTime 100Hz' to
    provide realtime support if you don't have the MIDISupport module
    and don't want to use the MIDI500 module
 d) allows the synth to be used with MIDI sequencers and
    MIDI file players that use only those part of the MIDI module that
    the MIDI500 module implements.


 Notice that these methods only work for the default port. When using
 any other port, you must feed events directly to the synth.


 The scheduler
 -------------
 The scheduler buffers MIDI events and inserts them into the MIDI
 buffer at the right time. When passing a MIDI event to the
 scheduler, you tell it when to insert the event into the MIDI
 buffer.

 The scheduler doesn't care about realtime, seconds, centiseconds and
 so on. Instead the scheduler uses 'ticks' to keep track of time.
 When/how the ticker is incremented depends on many things...

 The number of ticks per second defaults to 4000, but can be set to
 just about any value. The value is only used when converting a
 realtime value to ticks, eg. when incrementing the ticker by the
 no. of ticks that corresponds to a no. of samples at the configured
 output frequency.
 Notice that there can be rounding errors in this conversion; the
 best way to minimise this is to select a sensible no. of ticks per
 second; normally, the default value is perfectly OK, but it may
 sometimes be a good idea to set the ticks/second to the same as the
 output frequency (eg. 22050 or 44100). Higher values than that should
 never be used.

 Notice that the events must be scheduled in the correct order, that
 is, the ticker value for one event must be larger than the
 ticker value for the previous event, otherwise the order of the
 events may end up incorrect.

 Notice that the scheduler only works with the default port.


 In use
 ------
 If you don't have 16 bit sound, try the 16 bit sound emulator -
 available from http://www.riscos.org/links.html.

 If you have the MIDISupport module:
          *RMLoad HBP10GM
          *HBP10GM_RealTime MIDISUPPORT
          *HBP10GM_Config FREQ 22050
          *HBP10GM_Config POLY 16
          *MIDIConnect MIDIPort0 HBP10GM
          *HBP10GM_Playback 1
          ... play from !MidiWorks, !MelIDI, !Monolith or whatever
          *HBP10GM_Playback 0

 If you don't have the MIDISupport module, use MIDI500:
          *RMLoad HBP10GM
          *HBP10GM_RealTime MIDI500
          *HBP10GM_Config FREQ 22050
          *HBP10GM_Config POLY 16
          *HBP10GM_Playback 1
          ... use !MidiWorks or similar to play MIDI ...
          *HBP10GM_Playback 0

 If you don't want to use the MIDI500 module, use a 100Hz timer:
          *RMLoad HBP10GM
          *HBP10GM_RealTime 100Hz
          *HBP10GM_Config FREQ 22050
          *HBP10GM_Config POLY 16
          *HBP10GM_Playback 1
          ... use PlayMIDI to play a MIDI file ...
          *HBP10GM_Playback 0


 Implementation details
 ----------------------
 Controller #32 selects a program bank.
 Omni On and Omni Off is supported.
 Monophonic mode is not supported.
 Controllers volume, expression and pan are used to control the
 volume. Volume is logarithmic, expression is linear.
 Up to 32 ports can be used at the same time.


 MIDI note numbers
 -----------------

 Octave  C    C#   D    D#   E    F    F#   G    G#   A    A#   B
 ----------------------------------------------------------------
  0      0    1    2    3    4    5    6    7    8    9   10   11 
  1     12   13   14   15   16   17   18   19   20   21   22   23 
  2     24   25   26   27   28   29   30   31   32   33   34   35 
  3     36   37   38   39   40   41   42   43   44   45   46   47 
  4     48   49   50   51   52   53   54   55   56   57   58   59 
  5     60   61   62   63   64   65   66   67   68   69   70   71 
  6     72   73   74   75   76   77   78   79   80   81   82   83 
  7     84   85   86   87   88   89   90   91   92   93   94   95 
  8     96   97   98   99  100  101  102  103  104  105  106  107 
  9    108  109  110  111  112  113  114  115  116  117  118  119 
 10    120  121  122  123  124  125  126  127 
